home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48hor2 / grep.doc < prev    next >
Text File  |  1995-03-31  |  18KB  |  514 lines

  1. GREP: A UNIX-like text-search utility; better than "FIND" in MS-DOS. 
  2.  
  3. úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  4. 3 Mini-instructions: Type "GREP ?" at the 3 
  5. 3 DOS prompt for the grep help screen.    3 
  6. àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  7.  
  8. Used by the Goodies Disk FETCH batch file. The following documentation 
  9. is included for those who wish to use GREP by itself for their own 
  10. purposes. I suggest putting it in your DOS directory and using it as 
  11. an "upgrade" for DOS's "FIND" command.  -jkh- 
  12.  
  13. Portions of this documentation are copyright (c) 1990 Borland 
  14. International. All rights reserved. Used with permission. 
  15.  
  16.  
  17.   úÄÄÄÄÄÄÄÄÄÄ¿ 
  18.   3 OVERVIEW 3 
  19.   àÄÄÄÄÄÄÄÄÄÄù 
  20.  
  21. GREP (Global Regular Expression Print) is a powerful text-search 
  22. program derived from the UNIX utility of the same name. GREP searches 
  23. for a text pattern in one or more files or in its standard input 
  24. stream. 
  25.  
  26. Here's a quick example of a situation where you might want to use 
  27. GREP. Suppose you wanted to find out which text files in your current 
  28. directory contained the string "Elisabeth." You would issue the 
  29. command 
  30.  
  31.    grep Elisabeth *.txt 
  32.  
  33. and GREP would respond with a list of the lines in each file (if any) 
  34. that contained the string "Elisabeth."  (4DOS users can pipe the 
  35. output to LIST/S for convenient perusal and/or printing.) 
  36.  
  37. Note: the strings "elisabeth" and "ELISABETH" would *not* be 
  38. considered matches.  If you *do* want them to be matches, use 
  39.  
  40.    grep -i Elisabeth *.txt 
  41.  
  42. and the "-i" option (which means "-ignore case") would force grep to 
  43. treat uppercase and lowercase the same.  More about this and other 
  44. options later. 
  45.  
  46. GREP can do a lot more than match a single, fixed string. In the 
  47. section that follows, you'll see how to make GREP search for any 
  48. string that matches a particular pattern. 
  49.  
  50.  
  51.   úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  52.   3 Command-line syntax 3 
  53.   àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  54.  
  55. The general command-line syntax for GREP is 
  56.  
  57.   grep [options] searchstring [filespec ... ] 
  58.  
  59. options consist of one or more letters, preceded by a hyphen (-), 
  60. that let you change various aspects of GREP's behavior. 
  61.  
  62. searchstring gives the pattern to search for. 
  63.  
  64. filespec (a list of file specifications) tells GREP which files to 
  65. search. (If no file is specified, GREP searches its standard input; 
  66. this lets you use GREP with pipes and redirection.) 
  67.  
  68. In addition, the command 
  69.  
  70.    GREP ? 
  71.  
  72. prints a brief help screen showing GREP's command-line options, 
  73. special characters, and defaults. (See the description of the -u 
  74. command-line option for information on how to change GREP's 
  75. defaults.) 
  76.  
  77.  
  78.   úÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  79.   3 GREP options 3 
  80.   àÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  81.  
  82. In the command line, options are one or more single characters 
  83. preceded by a hyphen (-). Each individual character is a switch 
  84. that you can turn on or off: A plus symbol (+) after a character 
  85. turns the option on; a hyphen (-) after the character turns the 
  86. option off. 
  87.  
  88. The default is on; for example, -r means the same thing as -r+. You 
  89. can list multiple options individually (like this: -i -d -l), or 
  90. you can combine them (like this: -ild or -il, -d, and so on); it's 
  91. all the same to GREP. 
  92.  
  93. Here are the GREP option characters and their meanings: 
  94.  
  95.  
  96. Option     Meaning 
  97. ______ ____________________________________________________ 
  98.  
  99.  
  100.   -c   Count only: Prints only a count of matching lines. 
  101.        For each file that contains at least one matching 
  102.        line, GREP prints the file name and a count of the 
  103.        number of matching lines. Matching lines are not 
  104.        printed. 
  105.  
  106.   -d   Directories: For each filespec specified on the 
  107.        command line, GREP searches for all files that 
  108.        match the file specification, both in the directory 
  109.        specified and in all subdirectories below the 
  110.        specified directory. If you give a filespec without 
  111.        a path, GREP assumes the files are in the current 
  112.        directory. 
  113.  
  114.   -i   Ignore case: GREP ignores upper/lowercase 
  115.        differences (case folding). GREP treats all letters 
  116.        a to z as identical to the corresponding letters A 
  117.        to Z in all situations. 
  118.  
  119.   -l   List match files: Prints only the name of each file 
  120.        containing a match. After GREP finds a match, it 
  121.        prints the file name and processing immediately 
  122.        moves on to the next file. 
  123.  
  124.   -n   Numbers: Each matching line that GREP prints is 
  125.        preceded by its line number. 
  126.  
  127.   -o   UNIX output format: Changes the output format of 
  128.        matching lines to support more easily the UNIX 
  129.        style of command-line piping. All lines of output 
  130.        are preceded by the name of the file that contained 
  131.        the matching line. 
  132.  
  133.   -r   Regular expression search: The text defined by 
  134.        searchstring is treated as a regular expression 
  135.        instead of as a literal string. This option is on 
  136.        by default.  [Note to non-UNIX people: don't panic; 
  137.        "regular expression" is defined below.  -jkh-] 
  138.  
  139.   -u   Update options: GREP will combine the options given 
  140.        on the command line with its default options and 
  141.        write these to the GREP.COM file as the new 
  142.        defaults. (In other words, GREP is self- 
  143.        configuring.) This option allows you to tailor the 
  144.        default option settings to your own taste. If you 
  145.        want to see what the defaults are in a particular 
  146.        copy of GREP.COM, type 
  147.  
  148.         GREP ? 
  149.  
  150.        at the DOS prompt. Each option on the help screen 
  151.        will be followed by a + or a - depending on its 
  152.        default setting.  [See note below about using the 
  153.        -u option on a compressed GREP.COM.  -jkh-] 
  154.  
  155.   -v   Nonmatch: Prints only nonmatching lines. Only lines 
  156.        that do not contain the search string are 
  157.        considered to be nonmatching lines. 
  158.  
  159.   -w   Word search: Text found that matches the regular 
  160.        expression is considered a match only if the 
  161.        character immediately preceding and following 
  162.        cannot be part of a word. The default word 
  163.        character set includes A to Z, 0 to 9, and the 
  164.        underscore ( _ ). 
  165.  
  166.        An alternate form of this option lets you specify 
  167.        the set of legal word characters. Its form is 
  168.        -w[set], where set is any valid regular expression 
  169.        set definition (see below). 
  170.  
  171.        If you define the set with alphabetic characters, 
  172.        it is automatically defined to contain both the 
  173.        uppercase and lowercase values for each letter in 
  174.        the set (regardless of how it is typed), even if 
  175.        the search is case-sensitive. If you use the -w 
  176.        option in combination with the -u option, the new 
  177.        set of legal characters is saved as the default 
  178.        set. 
  179.  
  180.   -z   Verbose: GREP prints the file name of every file 
  181.        searched. Each matching line is preceded by its 
  182.        line number. A count of matching lines in each file 
  183.        is given, even if the count is zero. 
  184.  
  185.  
  186.   úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  187.   3 Order of precedence 3 
  188.   àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  189.  
  190. Remember that each of GREP's options is a switch: Its state 
  191. reflects the way you last set it. At any given time, each option 
  192. can only be on or off. Each occurrence of a given option on the 
  193. command line overrides its previous definition. Given this command 
  194. line, 
  195.  
  196.    grep -r -i- -d -i -r-  main( my*.c 
  197.  
  198. GREP runs with the -d option on, the -i option on, and the -r 
  199. option off.  The initial "-r" is lost due to the subsequent "-r-", 
  200. and so forth. 
  201.  
  202. You can install your preferred default setting for each option in 
  203. GREP.COM with the -u option. For example, if you want GREP to 
  204. default to a verbose search (-z on), you can install it with the 
  205. following command: 
  206.  
  207.    grep -u -z 
  208.  
  209. Use GREP ? to check the currently set defaults. 
  210.  
  211. [Note well: The -u option actually modifies the GREP.COM file itself. 
  212.  Therefore, do NOT use the -u option if you've compressed GREP.COM 
  213.  with LZEXE or any other "program packer".  If you have compressed 
  214.  GREP, and wish to customize it with the -u option, you must first 
  215.  unpack GREP to its original form (or recopy it from the Goodies 
  216.  Disk), use the -u option, and then compress it again.  -jkh-] 
  217.  
  218.  
  219.   úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  220.   3 The search string 3 
  221.   àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  222.  
  223. To use GREP well, you'll need to become proficient at writing 
  224. search strings. The value of searchstring defines the pattern GREP 
  225. searches for. A search string can be either a regular expression or 
  226. a literal string. 
  227.  
  228. In a regular expression, certain characters have special meanings: 
  229. They are operators that govern the search. 
  230.  
  231. In a literal string, there are no operators: Each character is 
  232. treated literally. 
  233.  
  234. You can enclose the search string in quotation marks to prevent 
  235. spaces and tabs from being treated as delimiters. The text matched 
  236. by the search string cannot cross line boundaries; that is, all the 
  237. text necessary to match the pattern must be on a single line. 
  238.  
  239. A regular expression is either a single character or a set of 
  240. characters enclosed in brackets. A concatenation of regular 
  241. expressions is a regular expression. 
  242.  
  243.  
  244.   úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  245.   3 Operators in regular expressions 3 
  246.   àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  247.  
  248. When you use the -r option (on by default), the search string is 
  249. treated as a regular expression (not a literal expression). The 
  250. following characters take on special meanings: 
  251.  
  252.  
  253. Option     Meaning 
  254. ______ ____________________________________________________ 
  255.  
  256.   ^    A circumflex at the start of the expression matches 
  257.        the start of a line.  E.g. "^hyde" only finds those 
  258.        lines that *begin* with "hyde". 
  259.  
  260.   $    A dollar sign at the end of the expression matches 
  261.        the end of a line.  E.g. "?$" only finds those lines 
  262.        that *end* with a question mark. 
  263.  
  264.   .    A period matches any character (single wildcard). 
  265.  
  266.   *    An expression followed by an asterisk wildcard 
  267.        matches ZERO OR MORE occurrences of that 
  268.        expression. For example, in "to*", the * operates on 
  269.        the expression o; it matches t, to, too, etc. (t 
  270.        followed by zero or more os), but doesn't match ta. 
  271.  
  272.   +    An expression followed by a plus sign matches ONE 
  273.        OR MORE occurrences of that expression: to+ matches 
  274.        to, too, etc., but not t. 
  275.  
  276.   [ ]  A string enclosed in brackets matches any character 
  277.        in that string, but no others. If the first 
  278.        character in the brackets is a circumflex (^), the 
  279.        expression matches any character EXCEPT the 
  280.        characters in the string. 
  281.  
  282.        For example, [xyz] matches x, y, or z, while [^xyz] 
  283.        matches everything but x, y, and z. You can 
  284.        specify a range of characters with two characters 
  285.        separated by a hyphen (-). These can be combined to 
  286.        form expressions (like [a-bd-z?], which matches the 
  287.        ? character and any lowercase letter except c). 
  288.  
  289.   \    The backslash escape character tells GREP to search 
  290.        for the literal character that follows it. For 
  291.        example, "\." matches a period instead of "any 
  292.        character." The backslash can be used to quote 
  293.        itself; that is, you can use \\ to indicate a 
  294.        literal backslash character in a GREP expression. 
  295.  
  296. Note: 
  297.  
  298. Four of the "special" characters ($, ., *, and +) don't have any 
  299. special meaning when used within a bracketed set. In addition, the 
  300. character ^ is only treated specially if it immediately follows the 
  301. beginning of the set definition (immediately after the "[" 
  302. delimiter). 
  303.  
  304. Any ordinary character not mentioned in the preceding list matches 
  305. that character (> matches >, # matches #, and so on). 
  306.  
  307.  
  308.   úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  309.   3 File specifications 3 
  310.   àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  311.  
  312. filespec tells GREP which files (or groups of files) to search. 
  313. filespec can be an explicit file name, or a "generic" file name 
  314. incorporating the DOS ? and * wildcards. In addition, you can enter 
  315. a path (drive and directory information) as part of filespec. If 
  316. you give filespec without a path, GREP searches the current 
  317. directory. 
  318.  
  319. If you don't specify any file specifications, input to GREP must 
  320. come from redirection (<) or a pipe (|). 
  321.  
  322.  
  323.   úÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ 
  324.   3 Some GREP examples 3 
  325.   àÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄù 
  326.  
  327. The following examples show how to combine GREP's features to do 
  328. different kinds of searches. They assume GREP's default settings 
  329. are unchanged. 
  330.  
  331.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  332.      3 Example 1 3 
  333.      àÄÄÄÄÄÄÄÄÄÄÄù 
  334. The search string here tells GREP to search for the word "main" with 
  335. no preceding lowercase letters ([^a-z]), followed by zero or more 
  336. occurrences of blank spaces (\ *), then a left parenthesis. 
  337.  
  338. Since spaces and tabs are normally considered to be command-line 
  339. delimiters, you must quote them if you want to include them as part 
  340. of a regular expression. In this case, the space after "main" is 
  341. quoted with the backslash escape character. You could also 
  342. accomplish this by placing the space in double quotes. 
  343.  
  344. Command line: 
  345.             grep -r [^a*z]main\ *( *.c 
  346.  
  347. Matches:    main(i:integer) 
  348.             main(i,j:integer) 
  349.             if (main  ()) halt; 
  350.  
  351. Does not match: 
  352.             mymain() 
  353.             MAIN(i:integer); 
  354.  
  355. Files searched: 
  356.             *.C in current directory. 
  357.  
  358.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  359.      3 Example 2 3 
  360.      àÄÄÄÄÄÄÄÄÄÄÄù 
  361. Because the backslash (\) and period (.) characters usually have 
  362. special meaning in path and file names, you must place 
  363. the backslash escape character immediately in front of them if 
  364. you want to search for them. The -i option is used here, so 
  365. the search is not case sensitive. 
  366.  
  367. Command line: 
  368.             grep -ri [a*c]:\\data\.fil *.c *.inc 
  369.  
  370. Matches:    A:\data.fil 
  371.             c:\Data.Fil 
  372.             B:\DATA.FIL 
  373.  
  374. Does not match: 
  375.             d:\data.fil 
  376.             a:data.fil 
  377.  
  378. Files searched: 
  379.             *.C and *.INC in current directory. 
  380.  
  381.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  382.      3 Example 3 3 
  383.      àÄÄÄÄÄÄÄÄÄÄÄù 
  384. This format basically defines how to search for a given word. 
  385.  
  386. Command line: 
  387.             grep -ri [^a*z]word[^a*z] *.doc 
  388.  
  389. Matches:    every new word must be on a new line. 
  390.             MY WORD! 
  391.             word--smallest unit of speech. 
  392.             In the beginning there was the WORD, and the WORD 
  393.  
  394. Does not match: 
  395.             Each file has at least 2000 words. 
  396.             He misspells toward as toword. 
  397.  
  398. Files searched: 
  399.             *.DOC in the current directory. 
  400.  
  401.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  402.      3 Example 4 3 
  403.      àÄÄÄÄÄÄÄÄÄÄÄù 
  404. This format defines a basic "word" search. 
  405.  
  406. Command line: 
  407.             grep -iw word *.doc 
  408.  
  409. Matches:    every new word must be on a new line. However, 
  410.             MY WORD! 
  411.             word: smallest unit of speech which conveys 
  412.             In the beginning there was the WORD, and 
  413.  
  414. Does not match: 
  415.             each document contains at least 2000 words! 
  416.             He seems to continually misspell "toward" as "toword." 
  417.  
  418. Files searched: 
  419.             *.DOC in the current directory. 
  420.  
  421.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  422.      3 Example 5 3 
  423.      àÄÄÄÄÄÄÄÄÄÄÄù 
  424. This is an example of how to search for a string with embedded spaces. 
  425.  
  426. Command line: 
  427.             grep "search string with spaces" *.doc *.c a:\work\myfile.* 
  428.  
  429. Matches:    This is a search string with spaces in it. 
  430.  
  431. Does not match: 
  432.             THIS IS A SEARCH STRING WITH SPACES IN IT. 
  433.             This search string has spaces in it, too. 
  434.  
  435. Files searched: 
  436.             *.DOC and *.C in the current directory, and MYFILE.* in a 
  437.             directory called \WORK on drive A. 
  438.  
  439.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  440.      3 Example 6 3 
  441.      àÄÄÄÄÄÄÄÄÄÄÄù 
  442. This example searches for any one of the characters " . : ? ' and , 
  443. at the end of a line. 
  444.  
  445. The double quote within the range is preceded by an escape character, 
  446. so it is treated as a normal character instead of as the ending quote 
  447. for the string. Also, the $ character appears outside of the quoted 
  448. string. This demonstrates how regular expressions can be concatenated 
  449. to form a longer expression. 
  450.  
  451. Command line: 
  452.             grep -rd "[ ,.:?'\"]"$ \*.doc 
  453.  
  454. Matches:    He said hi to me. 
  455.             Where are you going? 
  456.             In anticipation of a unique situation, 
  457.             Examples include the following: 
  458.             "Many men smoke, but fu man chu." 
  459.  
  460. Does not match: 
  461.             He said "Hi" to me 
  462.             Where are you going? I'm headed to the 
  463.  
  464. Files searched: 
  465.             *.DOC in the root directory and all its subdirectories on 
  466.             the current drive. 
  467.  
  468.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  469.      3 Example 7 3 
  470.      àÄÄÄÄÄÄÄÄÄÄÄù 
  471. This example ignores case and just prints the names of any files 
  472. that contain at least one match. The three command-line examples 
  473. show different ways of specifying multiple options. 
  474.  
  475. Command line: 
  476.             grep -ild " the " \*.doc 
  477.              or 
  478.             grep -i -l -d " the " \*.doc 
  479.              or 
  480.             grep -il -d " the " \*.doc 
  481.  
  482. Matches:    Anyway, this is the time we have 
  483.             do you think? The main reason we are 
  484.  
  485. Does not match: 
  486.             He said "Hi" to me just when I 
  487.             Where are you going? I'll bet you're headed 
  488.  
  489. Files searched: 
  490.             *.DOC in the root directory and all its subdirectories on 
  491.             the current drive. 
  492.  
  493.      úÄÄÄÄÄÄÄÄÄÄÄ¿ 
  494.      3 Example 8 3 
  495.      àÄÄÄÄÄÄÄÄÄÄÄù 
  496. This example redefines the current set of legal characters for a word 
  497. as the assignment operator (=) only, then does a word search. It matches 
  498. C assignment statements, which use a single equal sign (=), but not 
  499. equality tests, which use a double equal sign (==). 
  500.  
  501. Command line: 
  502.             grep -w[=] = *.c 
  503.  
  504. Matches:    i = 5; 
  505.             j=5; 
  506.             i += j; 
  507.  
  508. Does not match: 
  509.             if (i == t) j++; 
  510.             /* ======================= */ 
  511.  
  512. Files searched: 
  513.             *.C in the current directory. 
  514.